Reasonable care has been taken in the preparation of this
document and the software described herein. However, the
author makes no representations or warranties regarding the
fitness of the software for a particular purpose or its
merchantibility; moreover, the author assumes no responsibility
or liability for errors, omissions, bugs, or inaccuracies in
either the software or its documentation. Said software and
documentation are provided “as is" and are subject to revision
without prior notice.
TRADEMARKS:
Acrobat is a trademark of Adobe Systems, Inc. Code Warrior is a
trademark of Metrowerks, Inc. PowerMac and Macintosh are trademarks
of Apple Computer. Other trademarks and trade names are the property
of their respective holders.
UPDATES:
Updates will be posted at <pre>http://www.acroforms.com</pre>.
Bugs, feature requests, support inquiries and questions regarding
distribution of this software should be directed to <pre>kthomas@acroforms.com</pre>.
<!!>
<I><B> <FONT COLOR=#dddddd><RECT 0 0 800 900 >
<FONT COLOR=#006333>
Author: </B>
Kas Thomas
<B>
Developed using:</B>
Metrowerks Code Warrior Pro 5
PDFLib by Thomas Merz (tm@muc.de)
BBEdit Extension Interface SDK v7.0
(from http://www.barebones.com)
<B>
This documentation created using:</B>
BBEdit v5.0
PDF-Blit™ v1.0
<!!>
<FONT COLOR=#220000><h3>What Is PDF-Blit™?</h3><FONT COLOR=#000000>
PDF-Blit is an extension, or plug-in, for BBEdit (and BBEdit Lite), the text editor marketed by Bare Bones Software. The plug-in is designed to give a PDF export capability to BBEdit, thereby letting BBEdit users create attractive, richly formatted documents without having to use Distiller, Acrobat, or any other PDF authoring software. With PDF-Blit, you can output Portable Document Format files directly from BBEdit.
<FONT COLOR=#220000>
<h3>Features</h3><FONT COLOR=#000000>
PDF-Blit will let you create very attractive, colorful documents directly from BBEdit, in your choice of serif (Times-Roman), sans-serif (Helvetica), or fixed-width (Courier) typeface, at any point size, and with any line spacing. Not only that, but you can use italics, boldface type, headings, and colored type freely throughout your document (by appropriate use of HTML-style tags; see further below). This manual, for example, was created using BBEdit and PDF-Blit™. In fact, the raw text version of this document is included in the PDF-Blit™ distribution files, so that you can see how various tags were used to achieve various effects in this document.
PDF-Blit™'s powerful capabilities include:
• Choice of 12 default typefaces.
• Fonts in any point size, including fractional values.
• Leading (line spacing) of any magnitude, including fractional values.
• Text color can be varied on the fly.
• Typeface can be styled (italics, boldface, bold italics) on the fly.
• 6 heading sizes.
• Customizable tab width.
• Customizable character width. (Fonts can be condensed or expanded in one-percent increments.)
• Text justification option.
• User can set margins on all 4 edges of page.
• Choose from 7 page-transition effects (box-zoom, split, blinds, glitter, dissolve, wipe, and replace).
• Auto-page-numbering can be turned on or off.
• User-customizable header can be enabled/disabled.
• PDF file can be auto-opened in Acrobat Reader.
• HTML tags interpreted (see below).
• User control over PDF Document Info fields (Author, Title, Keywords).
<FONT COLOR=#220000>
<h3>Installation</h3><FONT COLOR=#000000>
You can install PDF-Blit by dragging it into your BBEdit Plug-Ins folder. The extension will load automatically when you start BBEdit. You should see “PDF-Blit...” in the Tools menu when BBEdit is running. (It will be grayed out until you have a document open, however.)
<FONT COLOR=#220000>
<h3>Basic Operation</h3><FONT COLOR=#000000>
You can output a PDF version of any file that's open in BBEdit's foremost window simply by choosing “PDF-Blit ...” from the Tools menu and clicking OK when the PDF-Blit dialog appears. Your original document will not be altered in any way. A new file, with the same name as the current document, but with “.pdf" appended to the name, will appear in the BBEdit default folder (the folder BBEdit is in). The new file will be a PDF file (filetype 'PDF ' and creator 'CARO') conforming to Version 1.3 of the PDF specification, suitable for viewing by Acrobat Reader 3.0 or higher.
<FONT COLOR=#220000>
<h3>Preferences</h3><FONT COLOR=#000000>
You can set various user preferences in PDF-Blit's setup dialog, which appears every time PDF-Blit is launched. The settings you choose here will persist across BBEdit sessions. That is, each time you launch PDF-Blit, you will see the same settings that you chose the <i>last</i> time you used PDF-Blit. Your settings will not be lost, even after you quit BBEdit.
<!!>
<FONT COLOR=#440000>
<h1>Advanced Options</h1><FONT COLOR=#220000>
<h3>Default Typeface</h3><FONT COLOR=#000000>
A drop-down menu allows you to select from 12 default typefaces for your document. The typefaces are Helvetica, Helvetica Bold, Helvetica Oblique, Helvetica Bold Oblique, Times-Roman, Times Bold, Times Oblique, Times Bold Oblique, Courier, Courier Bold, Courier Oblique, and Courier Bold Oblique. If you have left the “Interpret tags" checkbox unchecked (see below), the typeface that you select from the drop-down menu will remain the sole typeface used throughout your document. <i>If you wish to make use of bold, italics, or bold-italics at various places throughout your document, you need to check the “Interpret tags" checkbox and choose one of the three basic typefaces-Helvetica, Times-Roman, or Courier-as your default typeface.</i>
<FONT COLOR=#220000>
<h3>Point Size</h3><FONT COLOR=#000000>
You can choose any point size for the text in your document, including fractional values such as 9.8 or 13.6. For most documents, a default point size of 10 to 14 points works best.
<FONT COLOR=#220000>
<h3>Leading</h3><FONT COLOR=#000000>
Leading refers to the vertical spacing between lines of text. You can supply any leading value you want, but for most types of documents the leading value should be close in magnitude to the point size of the text. Use a higher leading value for greater space between lines; a lower value for more tightly packed lines. (A leading value that is three to four times the point size of the type will give your document a “double-spaced" look.)
<FONT COLOR=#220000>
<h3>Tabs</h3><FONT COLOR=#000000>
You can tell PDF-Blit how many spaces to insert for each Tab in your document. A value of from 3 to 6 works good for most documents, although if you are setting up special tables, you may want to try other values.
<FONT COLOR=#220000>
<h3>Character Width</h3><FONT COLOR=#000000>
The default value for character width is 100, meaning 100% of normal width. For condensed type, enter a value smaller than 100. (For example, a value of 75 means every character in your document will be 75% of normal width.) For expanded type, use a value greater than 100. Note that the value you supply here applies globally to every character in your document.
<FONT COLOR=#220000>
<h3>Transition Effect</h3><FONT COLOR=#000000>
A second drop-down menu lets you choose from seven different page-transition effects that will take place in Acrobat Reader as you page through an open PDF document. The effects apply globally to every page in a document. The default effect is <b>replace. Box, split, wipe, and blinds</B> implement familiar cinematic transition effects.
PDF-Blit allows you greater control over transition effects than the full commercial version of Acrobat 4.0 does! This feature alone makes PDF-Blit™ a very powerful tool.
<FONT COLOR=#220000>
<h3>Page Numbering</h3><FONT COLOR=#000000>
By checking the “Show Page Numbers" checkbox in PDF-Blit's setup dialog, you can make PDF-Blit number your document's pages for you. Page numbers will appear (in the default typeface) in the upper righthand corner of every page. <i>Note: To position the page number exactly where you want it, experiment with different Top Margin settings (below).
<b>Tip: To keep a page number from appearing on the title page (first page) of your document, create a page-sized white rectangle (see below) on that page, before any text. The first page is numbered before the rectangle is drawn, which means that you can overpaint the first page number with white by using the big-white-rect technique. </b></i>
<FONT COLOR=#220000>
<h3>Header Lines</h3><FONT COLOR=#000000>
You can make PDF-Blit™ print up to three header lines in the upper left corner of every page, by default, just by checking the “Show Headers" checkbox and entering text in the Author, Title, and Keywords text-edit areas in the lower portion of the setup dialog. Whatever you type in the Author box will appear as the first line of your header. Whatever you type in the Title area will appear on a second header line, and whatever you type in Keywords will appear on a third header line. To make any header line not appear, just delete all text from the appropriate text-edit box. (No header will appear at all, of course, unless you have checked the “Show Headers" checkbox.)
<FONT COLOR=#220000>
<h3>Justify Text</h3><FONT COLOR=#000000>
You can make PDF-Blit justify your document's text (flush right and flush left) by checking the Justify checkbox. But in order for justification to work properly, your document <i>must not contain hard returns at the end of every line.</i> Carriage returns must occur ONLY at paragraph endings, not at line endings. Fortunately, this is BBEdit's default behavior. (Soft-wrapping of text onscreen does not place hard returns in the actual document. So you can leave “soft wrapping" enabled.) Documents retrieved from DOS or Windows systems may not justify until you remove all the carriage returns and linefeeds from the line endings. Ditto for e-mail messages, which may contain hard returns at the ends of lines.
<B>Important:</b> In this version of PDF-Blit™, you cannot enable tag interpretation and text justification at the same time. This is because PDF-Blit™ does not (currently) cache whole lines of text when formatting is enabled. Therefore, you can have formatting (italics, bold, headings, colored type, etc.), or you can have text justification, but not both. If there is sufficient interest, we will fix this in a future upgrade. In the meantime, to enable the “Interpret Tags" checkbox, uncheck the Justify checkbox, and vice versa.
Note: To control column width when justification is enabled, set your left and right page margins appropriately. In this version of PDF-Blit™, the ability to create multiple columns of justified type on the same page is not implemented. Again, if there is sufficient interest, we will implement this in a future upgrade.
<FONT COLOR=#220000>
<h3>View in Acrobat</h3><FONT COLOR=#000000>
By checking the “View in Acrobat" checkbox, you are telling PDF-Blit to launch Acrobat or Acrobat Reader (whichever is present on the BBEdit default disk) and display your just-created PDF file in Acrobat when PDF-Blit is done. Of course, sufficient free memory to run Acrobat must exist in order for this to work properly. <i>After Acrobat (or Reader) launches, your document will come to the front and Acrobat will be the active application. BBEdit will continue to run in the background.</i>
If you do not wish to see your PDF document open in Acrobat, leave “View in Acrobat" unchecked.
<FONT COLOR=#220000>
<h3>Interpret Tags</h3><FONT COLOR=#000000>
PDF-Blit™ v1.0 has a rudimentary built-in ability to interpret HTML tags. But not <i>all</i> HTML tags. The tags that are supported at this time include:
• \<I> ... \</I> for italics.
• \<B> ...\ </B> for boldface.
• \<H1> thru \<H6> ... \</H1> thru \</H6> for headings.
• \<PRE> and \</PRE> for constant-width preformatted text (Courier).
• \<FONT COLOR=#RRGGBB>, where RRGGBB represents hex values for red, green, and blue color components.
Examples:
<I>This shows the use of \<I> for italics.</i>
<B>This shows the use of \<B> for boldface.
<I>This shows the use of \<B>\<I> for boldface italics.</I></B>
<pre>This shows the use of \<pre> for preformatted text.
<B>This shows preformatted boldface text via \<pre>\<B>.
<I>And of course you can combine tags</i> in almost any</pre> manner </b>you want.
<h1>Heading \<h1> looks like this.</h1>
<h2>Heading \<h2> looks like this.</h2>
<h3>Heading \<h3> looks like this.</h3>
<h4>Heading \<h4> looks like this.</h4>
<h5>Heading \<h5> looks like this.</h5>
<h6>Heading \<h6> looks like this.</h6>
<I><B>All other HTML tags are ignored and will not print (unless escaped as described in Note 4 below).</b></i>
Note 1: The HTML tags are not case-sensitive.
Note 2: Headings are always Times Bold.
Note 3: Style tags (bold, italics, etc.) should not be nested with heading tags (h1, h6, etc.).
Note 4: When tag interpretation is enabled, the angle brackets will not print unless they are escaped with a backslash, as in<b> \\<.</b>
<!!> <FONT COLOR=#000000>
<h4>Additional (Non-Standard) Tags</h4>
In addition to the standard HTML tags listed above, PDF-Blit™ recognizes some tags of its own:
• Use \<!!>to force a page break.
• Use \<#30>to force the file to end abruptly.
The former is useful when you are formatting a long document and need to be sure that a short section ends on a particular page.
The latter marking is useful as a workaround for a PDF-Blit™ bug that occasionally results in garbage characters at the very end of a file. By using \<#30> at the end of a file, you can prevent garbage characters from ever showing up.
<h4>Graphics Capability</h4>
PDFBlit™ incorporates one vector-graphics facility, for drawing rectangles. The special tag that invokes this facility is:
\<RECT XX YY WW HH>
where XX and YY are numbers representing the coordinates for the lower left corner of the rectangle and WW and HH are numbers representing the width and height, respectively, of the rectangle. <I>Note that all rectangles are solid-filled with the current text color.</i>
<b>Important:</b> In PDF space, the lower left corner of a page is the origin. The 'y' axis increases in the upward direction. Thus, to create a rectangle that covers an entire letter-sized page, you would write<b> \<RECT 0 0 612 792>.</b>
<!!>
<FONT COLOR=#220000>
<h3>Setting Margins</h3><FONT COLOR=#000000>
You can set the margins for all four edges of your page. The units are in printer's points (72 points to the inch). If you want half-inch margins left and right, set the left and right margin values to 36. For a two-inch margin at the top of the page, use a value of 144. And so on.
<FONT COLOR=#220000>
<h3>Author</h3><FONT COLOR=#000000>
The Author text-edit box lets you attach Author information to your PDF document. This information is seen in Acrobat Reader when the user chooses the “Document Info...” command. <I>Note: Any text you type here will also show up in the header on each page of a document if you have enabled “Show Headers.” </I>
<FONT COLOR=#220000>
<h3>Title</h3><FONT COLOR=#000000>
The Title text-edit box lets you attach Title information to your PDF document. This information is seen in Acrobat Reader when the user chooses the “Document Info...” command. <I>Note: Any text you type here will also show up in the second line of the header on each page of a document if you have enabled “Show Headers.” </I>
<FONT COLOR=#220000>
<h3>Keywords</h3><FONT COLOR=#000000>
The Keywords text-edit box lets you attach Keywords information to your PDF document. This information is seen in Acrobat Reader when the user chooses the “Document Info...” command. <I>Note: Any text you type here will also show up in the third header line on each page of a document if you have enabled “Show Headers.” </I>
<h1>A Short PDF-Blit™ FAQ</h1><FONT COLOR=#000000>
<b>How can I create a colored background for a page?</b>
In addition to enabling tag interpretation (see above), you must do three things:
1. Set the rectangle's color, by writing \<FONT COLOR=#RRGGBB> where RRGGBB are the hex values for the color components.
2. Create a rectangle covering the whole page. For example: \<RECT 0 0 700 800>.
3. Make sure you have inserted the foregoing code <b>prior to</b> any text that is to appear on the page. Otherwise, the rectangle will overwrite the text and you won't see any text. Also make sure that after you have created the rectangle that you reset the text color to a different color, say black (an RGB value of #000000). Otherwise, your text will be printed over the rectangle in the rectangle's own color, which of course will render the text invisible.
<B>Where can I find out about upgrades to PDF-Blit™?</b>
Visit <B>www.acroforms.com</b> on a regular basis. We do not operate a mailing list at present.
<B>Is source code available for PDF-Blit™?</b>
No, although a bare-bones framework (so to speak) for the code appeared in a late-1999 issue of <I>MacTech</i>. Go to <B>www.mactech.com</b> for details.
Code for the PDF-generating portions of PDF-Blit™ came from Thomas Merz's excellent PDFLib library. For that, visit <B>www.pdflib.com.</b>
<B>I would like to be able to put thin horizontal rules on a page. Is there a way to do this?</b>
Create one-pixel-deep rectangles at the positions where you want rules to appear. Remember, PDF-Blit™ will let you position rectangles with pixel accuracy. It may take you awhile to fit the text around your “rects” but with a little experimentation you should be able to achieve some nice effects.
<B>Can I print white text on a grey background?</b>
But of course! Just draw a gray rectangle (see above) in the appropriate place(s) and then specify a text color of #FFFFFF with a FONT tag. (But be sure to change the font color back to a non-white color later, after you're done drawing over the colored rect.)
<B>My headers and page numbers look awfully close to the top of the page. Is there a way to change this?</b>
Set your top margin to a more generous value (for example, 150).
<B>Some lines of text are going off the right edge of the page. Is there a way to keep this from happening?</b>
Set your right margin to a higher value. Or enter hard returns in your “problem lines.” But remember that if you change point sizes or typefaces, your lines may reflow in an unexpected manner.
<B>Is there a way to change the typeface or size or placement of the headers or page numbers?</b>
Not at this time. Sorry.
<B>Can I use condensed type? Will it affect text justification or right-hand page margins in any way?</B>
You can vary character widths in the setup dialog. Entering 50 (for 50% of normal) will give you very VERY tightly condensed (skinny) letters. A more tasteful value would be 85%. But in any case, text justification is not affected. Your text should justify normally (to the margins you selected) with character width values other than 100.
<B>Will PDF-Blit™ hyphenate words to achieve better justification?</b>
No attempt is made to hyphenate words. Even so, the justification should look pretty good, because we use a combination of word spacing adjustments, character spacing, and character width adjustment to achieve justification. The lack of hyphenation shouldn't be a factor in most cases. The only time it might be a factor is when the column width is small relative to the point size of the type. In that case, you should either turn justification off or use smaller type (or smaller margins).
<B>Is there any limit on the number of pages I can have in a document?</b>
No.
<B>Will I run out of memory if I try to convert a large document to PDF?</b>
No, you shouldn't. Large or small shouldn't matter, since the document is written to disk progressively as it is created. It isn't cached in memory.
<B>Sometimes when I make changes to a document and re-render it as PDF, the changes don't show up in the open document in Acrobat Reader.</b>
You have to close the old PDF document in Reader before re-rendering a new version of it. Otherwise, Reader still shows you the old version.
<B>Can I save my PDF document to a different directory or folder?</b>
Not presently. Right now, the PDF file is automatically written to the same folder where BBEdit resides.
<B>Can I somehow insert hidden signatures or copyright notices inside my PDF document?</b>
Yes. To some degree, that's what the Author, Title, and Keyword fields of the setup dialog are for. Text you type there will be embedded in the PDF document, visible only when the user selects “Document Info...” in Acrobat.
<B>When I begin a line with a heading, using \<h6> for example, I get an extra carriage return ahead of that line that I don't want. What can I do about it?</b>
This is a known bug (or feature, depending). You can try this workaround: Immediately before the heading, type a blank space. When you convert to PDF, the space will be removed, the heading will be flush-left, and the extra carriage return will no longer be there.
<B>PDF-Blit doesn't seem to like for a line to begin with a space. I notice it removes spaces at the start of a line. What can I do about this?</b>
Type Option-Space, instead of space, at the start of a line if you really intend to begin a line with a space, for example if you're trying to manually align preformatted text. Option-Space will solve the problem.
<B>Every once in a while, I'll go to output a document and all of a sudden I'll find that the default font has changed, by itself! What's going on?</b>
It doesn't change by itself. What happens is that if you <b>end</b> a tagged text file before you've closed the last tag, then whatever typeface you were in when the file was closed becomes your new default typeface. The answer should be obvious: Always close your tags. That means if you use \<pre>, you should later close it with \</pre>, especially if it's the last tagged area in the file. Leaving off the closing \</pre>tag will change your default typeface to Courier, possibly causing you to think Acrobat Reader can't find a needed font resource.
<B>Do I need to credit PDF-Blit in any documents I create with it?</b>
No.
<B>Can I put hypertext links in my PDF document using PDF-Blit™?</b>
Not presently. This is just one of many features we'll add to PDF-Blit™ if we get enough requests. If you have a feature you'd like to see added, contact the author at <B><pre>kt@acroforms.com.</pre></b>
And in the meantime, tell your friends about us! Remember the URL:<FONT COLOR=#880000> <pre>www.acroforms.com.</pre>
